*******************************************************************************
Blueberry Graphics(TM)             7910 W. Brookridge Dr., Middletown, MD 21769
                             http://ourworld.compuserve.com/homepages/blueberry
*******************************************************************************










                             VSA256 Graphics Library
                                For C Programmers

                                   Version 4.0
                                  March 17, 1996


                       Copyright Spyro Gumas, 1992 - 1996.
                               All Rights Reserved





                       Look what You get for Registering!!

          -    Royalty Free Use of VSA256 in Your Programs!
          -    Graphics Mouse Library!
          -    Joystick Library & Source Code!
          -    Image Processing Library & Source Code!
          -    32 Bit WATCOM C Compiler compatible library!
          -    3D Graphics Library!
          -    On line support through CompuServe!
          -    Printed Users Manual and Software Disk!
          -    Half Price upgrade to next version!

                            (See Page 7 for Details)
                        
                        










                                 Page: 1
                               
1.0 Introduction                                         4
     1.1 Revision History                                5
     1.2 Benefits of Registering                         7
     1.3 Distribution Files                              8
2.0 The Programming Environment                          9
     2.1 Setting Up The VESA Environment                 9
     2.2 Global Graphics Parameters                      9
     2.3 Compiler Compatibility                          10
3.0 Function Descriptions                                12
     3.1 VESA Configuration Functions                    12
          3.1.1 vsa_set_svga_mode                        12
          3.1.2 vsa_get_svga_mode                        13
          3.1.3 vsa_init                                 13
     3.2 Miscellaneous Functions                         14
          3.2.1 vsa_set_display_start                    14
          3.2.2 vsa_get_display_start                    14
          3.2.3 vsa_set_draw_page                        14
          3.2.4 vsa_get_draw_page                        15
          3.2.5 vsa_set_view_page                        15
          3.2.6 vsa_get_view_page                        15
          3.2.7 vsa_wait_vsync                           16
     3.3 Attribute Functions                             16
          3.3.1 vsa_set_color                            16
          3.3.2 vsa_get_color                            16
          3.3.3 vsa_set_text_color                       17
          3.3.4 vsa_get_text_color                       17
          3.3.5 vsa_set_clip_mode                        17
          3.3.6 vsa_get_clip_mode                        17
          3.3.7 vsa_set_triangle_clip_mode               17
          3.3.8 vsa_get_triangle_clip_mode               18
          3.3.9 vsa_set_viewport                         18
          3.3.10 vsa_get_viewport                        18
     3.4 Color Look Up Table Functions                   19
          3.4.1 vsa_read_color_register                  19
          3.4.2 vsa_write_color_register                 19
          3.4.3 vsa_read_color_block                     19
          3.4.4 vsa_write_color_block                    20
     3.5 Text Functions (Vector Stroked!)                20
          3.5.1 vsa_set_text_cursor                      21
          3.5.2 vsa_get_text_cursor                      21
          3.5.3 vsa_set_text_scale                       21
          3.5.4 vsa_get_text_scale                       22
          3.5.5 vsa_set_text_cursor_mode                 22
          3.5.6 vsa_get_text_cursor_mode                 22
          3.5.7 vsa_write_string                         22
          3.5.8 vsa_write_string_alt                     23
     3.6 Basic Drawing Functions                         23
          3.6.1 vsa_move_to                              23
          3.6.2 vsa_set_pixel                            23
          3.6.3 vsa_get_pixel                            24
          3.6.4 vsa_line_to                              24
          3.6.5 vsa_gouraud_line                         24
          3.6.6 vsa_rect                                 25
                                 Page: 2
                               
          3.6.7 vsa_rect_fill                            25
          3.6.8 vsa_triangle                             25
          3.6.9 vsa_triangle_fill                        25
          3.6.10 vsa_shaded_triangle                     26
          3.6.11 vsa_h_line                              26
          3.6.12 vsa_v_line                              26
     3.7 Specialized Drawing Functions                   27
          3.7.1 vsa_raster_line                          27
          3.7.2 vsa_get_raster_line                      27
          3.7.3 vsa_image_size                           27
          3.7.4 vsa_get_image                            28
          3.7.5 vsa_put_image                            28
4.0 Nitty Gritties                                       29
     4.1 Registration Information                        29
     4.2 Software License                                30
     4.3 Disclaimer                                      31
     4.4 Technical Support                               31
5.0 Application Notes                                    32
     5.1 Using Triangles                                 32
     5.2 Page Flipping                                   32
     5.3 Using Off Screen Video Memory                   32
     5.4 Expanding the VSA_FONT Character Set            33
6.0 Graphics Library Extensions                          33
6.1 The VSA256 GLE Developers Program                    33
6.2 Existing Graphics Library Extensions                 35
7.0 Appendix                                             36
     7.1 VSA.H Include File                              36
     7.2 VSA_FONT.H Include File                         38

























                                 Page: 3
                               

1.0 INTRODUCTION

  The VSA256 Graphics Library provides a C programmer with the tools necessary
to generate graphics output on a video adapter running with the Video
Electronics Standards Association (VESA) version 1.2 BIOS extensions.
The VESA BIOS extensions standardize the Super VGA (SVGA) graphics environment.
The name "VSA256" reflects the fact that this library is aimed at supporting
the 256 color video modes 100h, 101h, 103h, 105h, and 107h defined within the
VESA standard (See table in section 3.1.1).



                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        
                        

                                 Page: 4
                               
1.1 Revision History
Version 1.0 is the original SHAREWARE version of the VSA256 Graphics Library.

Version 1.1 is the SHAREWARE version of the VSA256 Graphics Library which
corrected some compiler compatibility problems and added the
vsa_get_raster_line function which was necessary for the TIFF256 Graphics
Library Extensions.  Some drawing errors were also corrected.

Version 2.0b is the REGISTERED version of the VSA256 Graphics Library.  Whereas
the VSA256 Graphics Library Version 1.x is shareware, Version 2.0b IS NOT
shareware and may only be used in accordance with the terms of the purchase
agreement.

Version 3.2 is presented to the general public in the true spirit of shareware.
I  no longer maintain a separate registered version of this library.  Version
3.2 of the VSA256 Graphics Library is presented as ShareWare with high hopes
that the programmers who use this library will feel good about sending in the
registration.

- Added Viewport Clipping          - Now works with Small, Medium,
- Added BitBLT functions.            Compact Large memory models with
- Added Vector Text: Infinitely      Borland (Already did so with
  scaleable and set to nearest       Microsoft)
  pixel, fonts are fully user      - Fixed "unresolved external
  definable!                         _fstrlen" linker error (Turbo C)
- Added Global Parameter           - Now text routines work with ALL
  VSA_ATI_COLOR for some ATI         video adapters
  cards.  (defaults to 0, set      - Made all functions in VSA.H See
  it to 1 if ATI card locks up.      external, no more "Multiple
  README.TXT)                        Declaration" warnings

Version 4.0 provides significantly increased drawing speeds over version 3.2
(see the VSA256 Revision Comparison Table).  In addition, real functionality
improvements are introduced into the library as a result of user feedback.

- MAJOR SPEED-UP of all drawing    - Added page flipping support for
  functions!                         double buffered drawing
- Changed vsa_set_viewport so      - Made the user definable FONT array
  that 'BOTTOM' can be set           expandable, to support foreign
  beyond bottom of displayable       languages
  video memory.  Now the user      - Added vsa_get... functions for all
  can use off screen memory to       existing vsa_set... functions
  store bitmaps for BitBLTs        - Made VSA_ATI_COLOR autodetect ATI
                                     cards









                                 Page: 5
                               

                        VSA256 Revision Comparison Table


Drawing Functions*       V1 V2 V3 V4      Control Functions         V1 V2 V3 V4
------------------------------------      -------------------------------------
vsa_move_to               *  *  *  *      vsa_set_svga_mode          *  *  *  *
vsa_set_pixel             *  *  *  *      vsa_get_svga_mode          *  *  *  *
vsa_get_pixel                   *  *      vsa_init                   *  *  *  *
vsa_line_to               * 3x 3x 6x      vsa_set_display_start      *  *  *  *
vsa_gouraud_line             *  * 2x      vsa_get_display_start      *  *  *  *
vsa_rect                  * 3x 3x 6x      vsa_set_draw_page                   *
vsa_rect_fill             *  *  * 4x      vsa_get_draw_page                   *
vsa_triangle                       *      vsa_set_view_page                   *
vsa_triangle_fill            *  * 2x      vsa_get_view_page                   *
vsa_shaded_triangle          *  * 2x      vsa_wait_vsync                   *  *
vsa_h_line                * 3x 3x 4x      vsa_set_color              *  *  *  *
vsa_v_line                *  *  * 2x      vsa_get_color                       *
vsa_raster_line           * 2x 2x 3x      vsa_set_text_color         *  *  *  *
vsa_get_raster_line          *  * 3x      vsa_get_text_color                  *
vsa_image_size                  *  *      vsa_set_clip_mode                *  *
vsa_get_image                   * 3x      vsa_get_clip_mode                   *
vsa_put_image                   * 3x      vsa_set_triangle_clip_mode          *
                                          vsa_get_triangle_clip_mode          *
                                          vsa_set_viewport                 *  *
                                          vsa_get_viewport                    *

Text Functions           V1 V2 V3 V4
-------------------------------------
vsa_set_text_cursor       *  *  *  *
vsa_get_text_cursor             *  *
vsa_set_text_scale              *  *      Color Functions           V1 V2 V3 V4
vsa_get_text_scale                 *      -------------------------------------
vsa_set_text_cursor_mode  *  *  *  *      vsa_read_color_register    *  *  *  *
vsa_get_text_cursor_mode           *      vsa_write_color_register   *  *  *  *
vsa_write_string          *  *  *  *      vsa_read_color_block       *  *  *  *
vsa_write_string_alt      *  *  *  *      vsa_write_color_block      *  *  *  *


          * For Drawing Functions, speed-up factors shown are relative to
            speed of VSA256 Version 1.0












                                 Page: 6
                               

1.2 Benefits of Registering
  If you use this program beyond an initial evaluation period, you must
register your use with a $34 remittance to the author .. me.  In addition to
the good feeling that you get for sustaining a late night hacking obsession,
you get the following benefits for registering:

1)   Royalty Free Use of VSA256 in Your Programs! Feel free to distribute your
     programs for profit with no royalty fees.  See section 4.2.

2)   Graphics Mouse Library!   Use this library to integrate Mouse input with
     your graphics applications.  Get precise updates of mouse position,
     update screen cursor, read mouse buttons, and more.  Invent your own
     graphical user interface, give your apps that professional feel, have
     tons of fun!

3)   Joystick Library with Source Code!   Integrate Joystick input with your
     graphics applications.  Write a flight simulator, boat driver, or your
     own unique use of this agile input device.

4)  IMP256 Image Processing Library and Source Code!  With this library you can
     learn all about image sharpening, embossing, blurring, color
     balancing, and enhancement.

5)   32 Bit WATCOM C Compiler compatible VSA256 and TIFF256 libraries!  Get the
     edge on performance.

6)   3D Graphics Library!   Don't live in a flat world.  Add the missing 3rd
     dimension to your creations.  This library lets you create 3d objects,
     set your view point, and perform 3d transformations including scale,
     offset, and rotation.  Supports wireframe, solid, and Gouraud shaded
     objects.  (Still being developed).

7)   On line support through CompuServe.

8)   Printed Users Manual and Current Version Software on Disk.

9)   One Half Price Upgrade to the next version, as it becomes available.

                                       AND
         As if that's not enough, for a measly $15 more,  you will get:

10)  TIFF256 Graphics Library Extensions.  This extension to the VSA256 library
     lets you read TIFF formatted graphic image files, display them, modify
     them, and write them back to disk.  Furthermore, anything that you
     create and display on the screen can be saved as a TIFF image file.
                        
                        
                        
                        
                        
                        

                                 Page: 7
                               

                                       AND

11) The following public domain full color TIFF image files to get you started:
                                   VENUS.TIF
                                   EARTH.TIF
                                   MOON.TIF
                                   MARS.TIF
                                   SATURN.TIF
                                   NEPTUNE.TIF
                                   SHUTTLE.TIF
                                   ASTRONTS.TIF
                                   WEATHER.TIF
                                   MANDRILL.TIF

                           (What, no Ginsu Knife Set?)

1.3 Distribution Files
The distribution of the VSA256 Graphics Library Version 4.0 consists of the 12
files listed below plus the drivers listed in Section 2.1.  These files are
archived in the file VSA256.ZIP.  To extract, just type 'PKUNZIP VSA256' in the
directory that you want the files extracted to.

VSA256MS.LIB                VSA256 Graphics Library (Microsoft C compatible).
VSA256BC.LIB                VSA256 Graphics Library(Borland C Compatible).
VSA.H                       VSA256 Include file required in your program.
VSA_FONT.H                  VSA256 Include file required in your program.
VSA_DEMO.C                  VSA256 Demonstration program (Source Code).
VSA_DEMO.EXE                VSA256 Demonstration program (Executable).
VSA_DEMO.MAK                VSA_DEMO Make file for Microsoft C.
VSA_DEMO.PRJ                VSA_DEMO Project file for Borland C/C++ V3.1.
VSA_DEMO.IDE                VSA_DEMO Project file for Borland C/C++ V4.0.
VSA256.TXT                  This text document.
ORDER.TXT                   Text file order form for registration and upgrades.
README.TXT                  Text file with important info.


















                                 Page: 8
                               

2.0 THE PROGRAMMING ENVIRONMENT

2.1 Setting Up The VESA Environment
  The VSA256 Graphics Library works with any (any?) IBM PC, XT, AT or
compatible computer equipped with a VESA compatible SVGA video adapter card
capable of 256 colors.  Most  of the video cards sold today are VESA compatible
with the VESA BIOS built in to the card.  A math coprocessor chip is not
required.
  For older SVGA video cards which are not VESA compatible, the VESA BIOS
Extensions must be loaded as a Terminate and Stay Resident (TSR) program before
using the VSA256 Graphics Library.  This is accomplished by executing the
appropriate driver or adding it to your AUTOEXEC.BAT file.  If your video
adapter card came with a VESA driver, use it.  Otherwise use one of the drivers
provided depending on the video adapter card installed in the PC as follows:

APPIAN                 \APPIAN\APVESA.EXE
ATI                    \ATI\VESA.COM
C&T                    \C&T\VESA451.COM (or VESA452.COM)
CIRRUS                 \CIRRUS\CRUSVESA.COM
EVEREX                 \EVEREX\EVRXVESA.COM
GENOA                  \GENOA\VESA.COM
OAK                    \OAK\37VESA.COM (or67VESA.COM)
ORCHID                 \ORCHID\ORCHDVSA.COM
PARADISE               \PARADISE\VESA.EXE
SIGMA                  \SIGMA\SIGVESA.COM
STB                    \STB\STB-VESA.COM
TECMAR                 \TECMAR\VGAVESA.COM
TRIDENT                \TRIDENT\VESA.EXE
VIDEO7                 \VIDEO7\V7VESA.COM

2.2 Global Graphics Parameters
  The VSA.H and VSA_FONT.H  files are used as include files during program
development.  These files includes all of the function prototypes and define
the global graphics parameters that describe the specific video adapter
installed in the PC (see Section 7).  The global graphics parameters are
initialized by the vsa_init function and are described below:

XResolution:      Unsigned, number of screen pixels across (x dimension).
YResolution:      Unsigned, number of screen pixels high (y dimension).
XCharResolution:  Unsigned, number of screen characters across (x dimension).
YCharResolution:  Unsigned, number of screen characters high (y dimension).
XCharSize:        Unsigned char, the character drawn cell width.
YCharSize:        Unsigned char, the character drawn cell height.
BitsPerPixel:     Unsigned char, the number of bits per pixel.
XLeft:            Int, the left edge of the screen clipping Viewport.
                        
                        
                        
                        
                        
                         

                                 Page: 9
                               
YTop:             Int, the top edge of the screen clipping Viewport.
XRight:           Int, the right edge of the screen clipping Viewport.
YBottom:          Int, the bottom edge of the screen clipping Viewport.
Text_X_Scale:     Float, multiplies XCharBase to get text width in pixels.
Text_Y_Scale:     Float, multiplies YCharBase to get text height in pixels.
XCharBase:        Unsigned, the fundamental text character width.
YCharBase:        Unsigned, the fundamental text character height.
ASC[96][72]:      Unsigned Char, the 2D array of character vertices.
VSA_ATI_COLOR     Int, set it to 1 if your ATI board locks up.  Defaults to 0.

  Note that there is a fundamental difference between how you use VSA.H and how
you use VSA_FONT.H.  The function prototypes and the global parameter
declarations are all "extern" in VSA.H.  This means that you can plop VSA.H
into
the top of each and every code module (file) which is part of your project.
VSA_FONT.H, on the other hand, declares and initializes the 'ASC[][]' array.
Since I want you, the programmer, to have access to the font definitions, I
couldn't make these parameter declarations "extern".  What this means for you
is that if you have multiple code modules (files), only include VSA_FONT.H in
one of the files.  Then put the following two lines of code at the top of each
and every other code module (file) in your project:

             extern unsigned far XCharBase, far YCharBase;
             extern unsigned char far ASC[][72];

2.3 Compiler Compatibility
  The VSA256MS.LIB was compiled using Microsoft's Quick C 2.5 and it seems to
also work well with Microsoft C 6.0 and 7.0.  I have received reports of
compatibility problems with Microsoft C 5.0.
  The VSA256BC.LIB was compiled using Borland's C/C++ 3.1 and it seems to also
work well with Borland C/C++ 3.0 and 4.0.  I have received conflicting reports
of compatibility problems with Borland's Turbo C 2.0 and 3.0.
  I appreciate any feedback that programmers send me along these lines so that
I can continue to improve this product.

                        Important Note for Borland Users:

  You MUST set the -Fs compiler option.  This tells the compiler to assume that
the Stack Segment equals the Data Segment.  In the Programmers IDE, you go to
Options / Compiler / Code Generation and select "Always" under the option
"Assume SS Equals DS".
  Why?  The VSA256 library can be used in Tiny, Small, Medium, Compact, and
Large memory models in both the Microsoft and Borland environments.  Microsoft
always puts the Stack Segment in the first Data Segment, but Borland sets up a
separate Stack Segment (for Compact and Large memory models) unless you specify
the -Fs option.  Failing to set -Fs will result in a "Stack Overflow!" error
when running code compiled in Compact or Large memory models.






                                 Page: 10
                               

                       Important Note for C++ Developers:

  I compiled and linked the VSA256 Graphics Library as a C library (not C++).
I know that Borland will give you grief if you try to link in my C library with
your C++ program.  You need to do one of two things:

1)   Write your program as a C program (.C extension, not .CPP)

                                   or

2)   Contact me and I can send you a C++ compiled version of the library.









































                                 Page: 11
                               

3.0 FUNCTION DESCRIPTIONS

This section describes the functions supported in the VSA256 Graphics Library.
To use these functions, link your program with the appropriate library listed
below depending on the compiler being used.

              Borland C, C++ or Turbo C   -    VSA256BC.LIB
              Microsoft C or Quick C      -    VSA256MS.LIB

  In the following sections each function is listed along with a definition of
its inputs and return values.  A description is provided followed by the
version in which the function became available.  Finally, if applicable,
comments are provided.

3.1 VESA Configuration Functions
3.1.1 vsa_set_svga_mode
Prototype:     unsigned vsa_set_svga_mode(unsigned video_mode);

Description:   This routine sets the video mode.  The mode number may be any
         of the standard VESA SVGA mode numbers as defined in the tables below.
         The mode is passed to this routine through the 'video_mode' parameter.
         This routine returns a 'fail_flag' = 0 if the call was a success (a 1
         for failure). It should be noted that this routine will also work with
         standard MDA, CGA, EGA, and VGA mode numbers, however the rest of the
         VSA256 functions will not necessarily work.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

WARNING: Use vsa_init Instead (Section 3.1.3)!  If you don't use vsa_init, then
the rest of the routines won't work because they depend on the global
parameters initialized by vsa_init;

                              VESA SVGA VIDEO MODES

GRAPHICS         Mode         Resolution     Colors
                 100h          640x400        256
                 101h          640x480        256
                 102h          800x600         16
                 103h          800x600        256
                 104h          1024x768        16
                 105h          1024x768       256
                 106h          1280x1024       16
                 107h          1280x1024      256









                                 Page: 12
                               

TEXT             Mode          Columns        Rows
                 108h             80           60
                 109h            132           25
                 10Ah            132           43
                 10Bh            132           50
                 10Ch            132           60

3.1.2 vsa_get_svga_mode
Prototype:     unsigned vsa_get_svga_mode(unsigned far *video_mode);

Description:   This routine gets the current video mode.  The mode is returned
          to the calling routine via the 'video_mode' pointer.  The mode number
          may be any of the standard VESA SVGA mode numbers as defined in
          Section 3.1.1. This routine returns a 'fail_flag' = 0 if the call was
          a success (a 1 for failure).

Availability:  In VSA256 Graphics Library Version 1.0 and up.

Comments:      Works in all VESA video modes.  Also works in MDA, CGA, EGA and
               VGA Modes.

3.1.3 vsa_init
Prototype:     unsigned vsa_init(unsigned video_mode);

Description: This routine sets the video mode and initializes the VESA graphics
          environment.  This routine must be called prior to the use of any of
          the routines in Sections 3.2 through 3.7.  The mode number may be any
          of the standard VESA SVGA mode numbers as defined in Section 3.1.1.
          If the mode number is not a VESA SVGA mode number, this routine will
          still set the desired video mode, however, the VESA graphics
          environment will not be initialized and subsequent calls to drawing
          routines will produce unpredictable results.  The mode is passed to
          this routine through the 'video_mode' parameter. This routine returns
          a 'fail_flag' = 0 if the call was a success.  For failures, the
          'fail_flag' has the following meaning:

          1  -  Can not get Super VGA Environment information.  Make sure
                VESA BIOS TSR is loaded.
          2  -  VESA BIOS TSR not loaded.  Need to load one.
          3  -  Specified Video Mode not supported by this video card.  Try
                another mode.
          4  -  Specified Video Mode was set but it is not one of the VESA
                standard modes.  VSA256 may not function properly.









                                 Page: 13
                               

          5  -  Can not get Super VGA Video Mode Data.  Make sure correct
                VESA BIOS TSR is loaded.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

Comments:      Starting with Version 3.0, VSA256 no longer prints out error
          messages automatically to the screen.  The programmer gets full
          status feed back via the 'fail_flag' and can do as he/she sees fit.
          Also note that VSA256 no longer cares if the specific VESA BIOS
          Extensions TSR being used supports text functions.  This is due to
          the new implementation of text using vector strokes (see
          vsa_write_string).

3.2 Miscellaneous Functions
3.2.1 vsa_set_display_start
Prototype:    unsigned vsa_set_display_start(unsigned x_strt, unsigned y_strt);

Description:   This routine sets the current start pixel address which is
          mapped to the upper left corner of the display.  This routine returns
          a 'fail_flag' = 0 if the call was a success (a 1 for failure).

Availability:  In VSA256 Graphics Library Version 1.0 and up.

Comments:      Don't bother with this unless you are hard core.  Use
               vsa_set_draw_page and vsa_set_view_page instead!

3.2.2 vsa_get_display_start
Prototype:     unsigned vsa_get_display_start(unsigned far *x_strt,
                                             unsigned far *y_strt);

Description:  This routine gets the current start pixel address which is mapped
          to the upper left corner of the display.  This routine returns a
          'fail_flag' = 0 if the call was a success (a 1 for failure).

Availability:  In VSA256 Graphics Library Version 1.0 and up.

Comments:      See vsa_get_draw_page and vsa_get_view_page also!

3.2.3 vsa_set_draw_page
Prototype:     void vsa_set_draw_page(int page);

Description:   This routine sets the current DRAW_PAGE in video memory to
          'page'.  All drawing actions occur into the current DRAW_PAGE of









                                 Page: 14
                               
          memory.  This routine is useful when you want to display from one
          portion of video memory (see vsa_set_view_page) while drawing into
          another.
              To determine the total available number of pages in video
          memory, divide the total available video RAM size by the display
          area.  For example a 1MB SVGA card running in 640 x 480 mode has 3.4
          pages (you can reasonably use pages 0, 1, and 2 for a total of 3
          pages).  Setting 'page' to a value beyond the number of existing
          pages will cause unpredictable stuff.   After vsa_init, the
          DRAW_PAGE defaults to 0.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

Comments:      Page flipping (Ping Pong Buffering or Double Buffering) is
               a really cool thing to do because it makes your redraws look
               instantaneous (see Sec. 5.2).

3.2.4 vsa_get_draw_page
Prototype:     int vsa_get_draw_page(void);

Description:   This routine returns the current DRAW_PAGE.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

3.2.5 vsa_set_view_page(int page);
Prototype:    void vsa_set_view_page(int page);

Description:   This routine sets the current VIEW_PAGE in video memory to
          'page'.  The current screen display comes from the VIEW_PAGE of
          memory.  This routine is useful when you want to display from one
          portion of video memory while drawing into another (see
          vsa_set_draw_page). To determine the total available number of pages
          in video memory, divide the total available video RAM size by the
          display area.  For example a 1MB SVGA card running in 640 x 480 mode
          has 3.4 pages (you can reasonably use pages 0, 1, and 2 for a total
          of 3 pages).  Setting 'page' to a value beyond the number of existing
          pages will cause unpredictable stuff.   After vsa_init, the VIEW_PAGE
          defaults to 0.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

Comments:      Page flipping (Ping Pong Buffering or Double Buffering) is
               a really cool thing to do because it makes your redraws look
               instantaneous (see Sec. 5.2).









                                 Page: 15
                        

3.2.6 vsa_get_view_page
Prototype:     int vsa_get_view_page(void);

Description:   This routine returns the current VIEW_PAGE.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

3.2.7 vsa_wait_vsync
Prototype:     void vsa_wait_vsync(void );

Description:   This routine waits until the beginning of the CRTs' vertical
          retrace period before returning control to the calling program.  If
          vsa_wait_vsync is called while the CRT is in vertical retrace, this
          routine waits until the completion of the current retrace period and
          the completion of the following active scan and then returns at the
          beginning of the next vertical retrace period.  The programmer can
          use this function to precede drawing functions which must be executed
          during CRT Vertical Retrace.  The programmer is assured the full
          retrace time for his use.

Availability:  In VSA256 Graphics Library Version 3.0 and up.

Comments:      Try using vsa_wait_vsync just prior to each vsa_set_view_page
               call to get rid of flicker effects (see Sec. 5.2).

3.3 Attribute Functions
3.3.1 vsa_set_color
Prototype:     void vsa_set_color(unsigned color);

Description:   This routine sets the current drawing color which is used in
          drawing pixels, lines, rectangles, and triangles.  The "color" is an
          8 bit value from 0 to 255 which is used to index in to the Color Look
          Up Table (see Section 3.4).

Availability:  In VSA256 Graphics Library Version 1.0 and up.


3.3.2 vsa_get_color
Prototype:     unsigned vsa_get_color(void);

Description:   This routine returns the current drawing color.

Availability:  In VSA256 Graphics Library Version 4.0 and up.









                                 Page: 16
                               

3.3.3 vsa_set_text_color
Prototype:     void vsa_set_text_color(unsigned color);

Description:   This routine sets the current text color which is used in
          drawing text.  The "color" is an 8 bit value from 0 to 255 which is
          used to index in to the Color Look Up Table (see Section 3.4).  Since
          the text is drawn using vector strokes, the background is unaffected
          by newly drawn text.  Note: this also means that drawing a text
          'space' character does nothing but index the text pointer.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.3.4 vsa_get_text_color
Prototype:     unsigned vsa_get_text_color(void);

Description:   This routine returns the current text color.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

3.3.5 vsa_set_clip_mode
Prototype:     void vsa_set_clip_mode(unsigned mode);

Description:   This routine sets the Viewport clipping mode ON if 'mode' = 1,
          OFF otherwise.  After vsa_init, the default is ON.

Availability:  In VSA256 Graphics Library Version 3.0 and up.

3.3.6 vsa_get_clip_mode
Prototype:     unsigned vsa_get_clip_mode(void);

Description:   This routine returns the Viewport clipping mode.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

3.3.7 vsa_set_triangle_clip_mode
Prototype:     void vsa_set_triangle_clip_mode(unsigned mode);

Description:   This routine sets the Triangle clipping mode ON if 'mode' = 1,
          OFF otherwise. After vsa_init, the default is ON.  This function only
          affects clipping for triangles drawn with vsa_triangle,












                                 Page: 17
                               
          vsa_triangle_fill, and vsa_shaded_triangle.  For triangle clipping to
          be on, both Viewport clipping mode AND Triangle clipping mode must be
          on.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

Comments:      See Section 5.1 for a short discussion about this.

3.3.8 vsa_get_triangle_clip_mode
Prototype:     unsigned vsa_get_triangle_clip_mode(void);

Description:   This routine returns the Triangle clipping mode.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

3.3.9 vsa_set_viewport
Prototype:     void vsa_set_viewport(int left,int top,int right,int bottom);

Description:   This routine sets the global Viewport clipping parameters XLeft,
         YTop, XRight, and YBottom. Note that vsa_init initializes these values
          to the full screen dimensions for the selected video mode.  Viewport
          clipping is turned on and off through the vsa_set_clip_mode function.
          By default, clip mode is ON after vsa_init.
             When clip mode is ON, all items drawn on the screen through VSA256
          functions are clipped to the screen Viewport rectangle defined by
          XLeft, YTop, XRight, and YBottom.
            NOTE:  Triangles will only be clipped if BOTH Viewport clipping AND
          Triangle clipping are on (see vsa_set_triangle_clip_mode).

Availability:  In VSA256 Graphics Library Version 3.0 and up.

Comments:      If you have enough video RAM, you can set 'BOTTOM' past the
          bottom of the screen.  Then you can draw things down there (like
          buttons) and BitBLT them up to the displayed area as needed (see
          Sec. 5.3).

3.3.10 vsa_get_viewport
Prototype:     void vsa_get_viewport(int far *pleft,int far *ptop,
                                    int far *pright,int far *pbottom);

Description:   This routine returns the global Viewport clipping parameters
          XLeft, YTop, XRight, and YBottom via the pointers '*pleft', '*ptop',
          '*pright', and '*pbottom' respectively.

Availability:  In VSA256 Graphics Library Version 4.0 and up.








                                 Page: 18
                               

3.4 Color Look Up Table Functions
  The Color Look Up Table consists of 256 registers and each register stores an
18 bit value defining 6 bit levels for each of red, green, and blue.  The
drawing functions index into the Color Look Up Table with an 8 bit value
(usually set with vsa_set_color) to determine the drawing color. With the
following functions, the Color Look Up Table can be read or modified one
register at a time or all at once in a block operation.

3.4.1 vsa_read_color_register

Prototype:     void vsa_read_color_register(unsigned index,unsigned char far
                  *redptr,unsigned char far *grnptr,unsigned char far *bluptr);

Description:   This routine reads the value of one of the 256 color registers
         as defined by 'index'. Pointers to the red, green, and blue components
          of the color are returned (6 bits each for red, green, and blue).

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.4.2 vsa_write_color_register

Prototype:     void vsa_write_color_register(unsigned index,unsigned char red,
                                     unsigned char green,unsigned char blue);

Description:   This routine writes the value of one of the 256 color registers
          as defined by 'index'.  The calling routine provides 'red', 'green',
          and 'blue' components of the color (6 bits each for red, green, and
          blue).

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.4.3 vsa_read_color_block
Prototype:     void vsa_read_color_block(unsigned start,unsigned count,
                                         unsigned char far *array);

Description:   This routine reads 'count' (Range: 1 to 256) consecutive color
          registers starting at 'start' (Range: 0 to 255) within the Color Look
          Up Table.  The 'count' must be less than or equal to 256 - 'start'.
          The values read from the color registers are returned from this
          routine in 'array[]'.  Each element of 'array[]' is a byte, and the
          size of 'array[]' is equal to three times 'count'.  Every three bytes
          in 'array[]' represents the red, green, and blue color values










                                 Page: 19
                               
         respectively for one color register. Each color component (red, green,
          or blue) is a byte value but only ranges from 0 to 63.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.4.4 vsa_write_color_block
Prototype:     void vsa_write_color_block(unsigned start,unsigned count,
                                         unsigned char far *array);

Description:   This routine writes 'count' (Range: 1 to 256) consecutive color
          registers starting at 'start' (Range: 0 to 255) within the Color Look
          Up Table.  The 'count' must be less than or equal to 256 - 'start'.
          The values loaded into the color registers are passed to this routine
          in 'array[]'.  Each element of 'array[]' is a byte, and the size of
          'array[]' is equal to three times 'count'.  Every three bytes in
          'array[]' represents the red, green, and blue color values
         respectively for one color register. Each color component (red, green,
          or blue) is a byte value but only ranges from 0 to 63.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.5 Text Functions (Vector Stroked!)
  Starting with VSA256 Version 3.0, text support has been completely REVAMPED!
The library no longer relies on the video card manufacturers BIOS to get text
support.  Instead each character is drawn using 2D vector strokes.  The
advantages are as follows:

     - Text now works with ALL video cards!
     - Now text is Infinitely scaleable.
     - Text positioning resolution is down to 1 pixel.
     - Background color is preserved.
     - The programmer can define his own fonts in VSA_FONT.H (see Sec.
       5.4)

Some minor incompatibilities with VSA256 version 2.0 were introduced due to
the changes and they are as follows:

     - vsa_write_string now takes x,y (in pixel coordinates) instead
       of row,col (in character coordinates) as the first two
       parameters.
     - The vsa_write_char function was deleted.
     - The supported ASCII characters are the printable characters
       from ASCII code 32 to ASCII code 127.










                                 Page: 20
                               

Your existing code should take very little editing to make these changes,
especially if you write a macro to edit all occurrences of vsa_write_string as
follows:

  OLD - vsa_write_string(row,col,color,text);

  NEW - vsa_write_string(col*XCharSize,row*YCharSize,color,text);

3.5.1 vsa_set_text_cursor
Prototype:     void vsa_set_text_cursor(int x,int y);

Description:   This routine sets the current text cursor position to 'x,y' in
          pixel coordinates.  The current text cursor position is only used
          by vsa_write_string_alt.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

Comments:      Note that with Rev 3.0 this function changed to pixel
               coordinates to support vector stroked fonts.

3.5.2 vsa_get_text_cursor
Prototype:     void vsa_get_text_cursor(int far *px,int far *py);

Description:   This routine gets the current text cursor position and returns
          the x and y positions via the pointers '*px' and '*py' respectively.
          The returned positions are in pixel coordinates.  The current text
          cursor position is only used by vsa_write_string_alt.

Availability:  In VSA256 Graphics Library Version 3.0 and up.

3.5.3 vsa_set_text_scale
Prototype:     void vsa_set_text_scale(float x_scale,float y_scale);

Description:   This routine sets the x and y scale factors for text drawn with
          the vsa_write_string and vsa_write_string_alt routines. The 'x_scale'
          and 'y_scale' scale factors are applied to the global parameters
          XCharBase and YCharBase respectively to determine the drawn text
          character width and height in pixels.  Since these scale factors are
          floating point, continuously and infinitely scaleable text characters
          are possible.
            This routine automatically adjusts the global parameters XCharSize,
          YCharSize, XCharResolution and YCharResolution to their appropriate
          values.  After vsa_init, the x_scale and y_scale factors both default
          to 1.0.

Availability:  In VSA256 Graphics Library Version 3.0 and up.






                                 Page: 21
                               
3.5.4 vsa_get_text_scale
Prototype:    void vsa_get_text_scale(float far *px_scale,float far *py_scale);

Description:   This routine returns the x and y scale factors used for text via
          the pointers '*px' and '*py' respectively.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

3.5.5 vsa_set_text_cursor_mode
Prototype:     void vsa_set_text_cursor_mode(unsigned mode);

Description:   This routine determines the mode of the text cursor operation.
         If 'mode' is '0' (the default after calling vsa_init), the text cursor
          is not updated after a new text string is written with
          vsa_write_string or vsa_write_string_alt. If 'mode' is '1', then the
          text cursor is moved to the end of the text string after executing
          vsa_write_string or vsa_write_string_alt.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

Comments:      If the text cursor mode is set to '1', the programmer may
          override the cursor operation as follows.  If a '\r' is placed at the
          end of the text string, the text cursor X value will reset to the
          beginning of the text string (equivalent to a carriage return).  If a
          '\n' is placed at the end of the text string, the cursor Y value
          advances by YCharSize pixels (equivalent to a line feed).  Putting
         '\r\n' at the end of a text string results in a line feed and carriage
          return.

3.5.6 vsa_get_text_cursor_mode
Prototype:     unsigned vsa_get_text_cursor_mode(void);

Description:   This routine returns the mode of the text cursor operation.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

3.5.7 vsa_write_string
Prototype:     void vsa_write_string(int x,int y,unsigned color,
                                     char far *string);

Description:   This routine writes a null terminated text string 'string' at
          position (x,y).  The text is written with the 'color' passed to this
          routine. After execution, if the text cursor mode is '0', the text
          cursor remains at 'x,y', otherwise it is set to the end of the text
          string just written (see comments in section 3.5.5).








                                 Page: 22
                               

Availability:  In VSA256 Graphics Library Version 1.0 and up.

Comments:      This routine was redefined in version 3.0 to support the new
          vector stroked fonts.  The text is drawn with vector strokes at the
          scale factor determined by the vsa_set_text_scale routine.  Full 2D
          clipping is performed according to the values set with the
          vsa_set_clip_mode and vsa_set_viewport routines.

3.5.8 vsa_write_string_alt
Prototype:     void vsa_write_string_alt(char far *string);

Description:  This routine writes a null terminated text string 'string' at the
          current text cursor position as determined by vsa_set_text_cursor.
          The text is written with the current text color.  After execution, if
          the text cursor mode is '0', the current text cursor remains
          unchanged, otherwise it is set to the end of the text string just
          written (see comments in section 3.5.5).

Availability:  In VSA256 Graphics Library Version 1.0 and up.

Comments:      This routine was redefined in version 3.0 to support the new
          vector stroked fonts.  The text is drawn with vector strokes at the
          scale factor determined by the vsa_set_text_scale routine.  Full 2D
          clipping is performed according to the values set with the
          vsa_set_clip_mode and vsa_set_viewport routines.

3.6 Basic Drawing Functions
3.6.1 vsa_move_to
Prototype:     void vsa_move_to(int x,int y);

Description:   This routine sets the current cursor position to 'x,y'.  The
          current cursor position is used by the vsa_line_to, vsa_rect_fill,
          and vsa_rect functions.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.6.2 vsa_set_pixel
Prototype:     void vsa_set_pixel(int x,int y);

Description:   This routine draws a single pixel at 'x,y' with the current
               drawing color.

Availability:  In VSA256 Graphics Library Version 1.0 and up.









                                 Page: 23
                               
3.6.3 vsa_get_pixel
Prototype:     unsigned vsa_get_pixel(int x,int y);

Description:   This routine returns the current pixel value at screen
               coordinates 'x,y'.

Availability:  In VSA256 Graphics Library Version 3.0 and up.

Comments:      Unpredictable things may happen if you try to get a pixel that
               is outside of the XResolution-1 screen dimensions.

3.6.4 vsa_line_to
Prototype:     void vsa_line_to(int x,int y);

Description:   This routine draws a line from the current cursor position to
          'x,y' with the current drawing color.  Then the current cursor
          position is moved to 'x,y'.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.6.5 vsa_gouraud_line
Prototype:     void vsa_gouraud_line(int x0,int c0,int x1,int c1,int y);

Description:   This routine draws a color interpolated line from the 'x0,y'
          to 'x1,y1'.  The pixel color value is linearly varied from a starting
          value of 'c0' at 'x0,y' to an ending value of 'c1' at 'x1,y'.  This
          technique of color interpolation is named Gouraud shading after the
          famous Joe-Bob** Not Really! Gouraud ... a French guy.  Valid values
          for 'c0' and 'c1' are 0 through 255 and serve as indexes into the
          Color Look Up Table. Gouraud shaded lines serve as a fundamental
          drawing element for realistic 3-D graphics.  The current cursor
          position remains unaffected by this routine.

Availability:  In VSA256 Graphics Library Version 2.0 and up.

3.6.6 vsa_rect
Prototype:     void vsa_rect(int x,int y);

Description:  This routine draws a rectangle from the current cursor position
              to the rectangles diagonal position 'x,y' with the current color.

Availability:  In VSA256 Graphics Library Version 1.0 and up.











                                 Page: 24
                               

3.6.7 vsa_rect_fill
Prototype:     void vsa_rect_fill(int x,int y);

Description:   This routine draws a filled rectangle from the current cursor
          position to the rectangles diagonal position 'x,y' with the current
          color.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.6.8 vsa_triangle
Prototype:     void vsa_triangle(int x0,int y0,int x1,int y1,int x2,int y2);

Description:   This routine draws a triangle defined by the 3 vertices 'x0,y0',
          'x1,y1', and 'x2,y2'.  The triangle is drawn with the current drawing
          color.  The current cursor position remains unaffected by this
          routine.

Availability:  In VSA256 Graphics Library Version 4.0 and up.

Comments:      If Triangle clip mode is off (see vsa_set_triangle_clip_mode),
               triangle drawing is significantly faster (see Sec. 5.1).

3.6.9 vsa_triangle_fill
Prototype:    void vsa_triangle_fill(int x0,int y0,int x1,int y1,int x2,int
y2);

Description:   This routine draws a filled triangle defined by the 3 vertices
          'x0,y0', 'x1,y1', and 'x2,y2'.  The triangle is drawn with the
          current drawing color. The current cursor position remains unaffected
          by this routine.

Availability:  In VSA256 Graphics Library Version 2.0 and up.

Comments:      If Triangle clip mode is off (see vsa_set_triangle_clip_mode),
               triangle drawing is significantly faster (see Sec. 5.1).

3.6.10 vsa_shaded_triangle
Prototype:     void vsa_shaded_triangle(int x0,int y0,int c0,int x1,int y1,
                                       int c1,int x2,int y2,int c2);

Description:   This routine draws a color interpolated triangle defined by the
          3 vertices 'x0,y0', 'x1,y1', and 'x2,y2'.  The pixel color value is
          linearly varied in 2 dimensions across the surface of the triangle
          using the values 'c0', 'c1', and 'c2' as the starting colors at the








                                 Page: 25
                               
          respective vertices.  This technique of color interpolation is named
          Gouraud shading after the famous Joe-Bob** Not Really! Gouraud ... a
          French guy.  Valid values for 'c0', 'c1', and 'c2' are 0 through 255
          and serve as indexes into the Color Look Up Table.  Gouraud shaded
          triangles serve as a fundamental drawing element for realistic 3-D
          graphics.  (Basically, most 3-D surfaces can be constructed out of
          shaded triangles).  The current cursor position remains unaffected
          by this routine.

Availability:  In VSA256 Graphics Library Version 2.0 and up.

Comments:      If Triangle clip mode is off (see vsa_set_triangle_clip_mode),
               triangle drawing is significantly faster (see Sec. 5.1).

3.6.11 vsa_h_line
Prototype:     void vsa_h_line(int    y,int x0,int x1);

Description:   This routine draws a horizontal line from 'x0,y' to 'x1,y'.
          The line is drawn with the current drawing color.  For horizontal
          lines this function is quicker than the vsa_line_to function.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.6.12 vsa_v_line
Prototype:     void vsa_v_line(int x,int y0,int y1);

Description:   This routine draws a vertical line from 'x,y0' to 'x,y1'.  The
          line is drawn with the current drawing color.  For vertical lines
          this function is quicker than the vsa_line_to function.

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.7 Specialized Drawing Functions
3.7.1 vsa_raster_line
Prototype:     void vsa_raster_line(int x0,int x1,int y,
                                    unsigned char far *array);

Description: This routine draws a horizontal raster line from 'x0,y' to 'x1,y'.
        The 'array[]' values specify each pixel's color value.  If x0 <= x1,
        then 'array[0]' defines the color of the first pixel in the line at
        'x0,y'.  If x1 < x0, then 'array[0]' defines the color of the first
        pixel in the line at 'x1,y'.  The vsa_raster_line routine is
        typically used to draw images on the display one raster line at a time.










                                 Page: 26
                               

Availability:  In VSA256 Graphics Library Version 1.0 and up.

3.7.2 vsa_get_raster_line
Prototype:     void vsa_get_raster_line(int x0,int x1,int y,
                                        unsigned char far *array);

Description:  This routine gets a horizontal raster line from 'x0,y' to 'x1,y'.
          The 'array[]' is loaded with each pixel's color value.  If x0 <= x1,
          then 'array[0]' defines the color of the first pixel in the line at
          'x0,y'.  If x1 < x0, then 'array[0]' defines the color of the first
          pixel in the line at 'x1,y'. The vsa_get_raster_line routine is
          typically used to read back images already drawn on the display one
          raster line at a time.

Availability:  In VSA256 Graphics Library Version 2.0 and up.

Comments:      This routine limits x0 and x1 within the range of 0 and
         XResolution-1. If x0 goes negative, the first element of 'array' holds
          the pixel at x=0 and less than x1-x0+1 pixels will be  loaded  into
          'array'. Likewise, if x1 is greater than XResolution-1, less than x1-
          x0+1 pixels will be loaded  into 'array'.

3.7.3 vsa_image_size
Prototype:     unsigned long vsa_image_size(int x0,int y0,int x1,int y1);

Description:   This routine calculates the size of the image defined within a
          rectangle bound by 'x0,y0' and 'x1,y1'.  The size of the image plus 4
          is returned.
             The vsa_image_size routine is typically used to determine the size
          of the image array to be allocated and used in the vsa_get_image and
          vsa_put_image routines.

Availability:  In VSA256 Graphics Library Version 3.0 and up.

3.7.4 vsa_get_image
Prototype:     void vsa_get_image(int x0,int y0,int x1,int y1,
                                 unsigned char huge *image_array);

Description:   This routine gets the image defined in the rectangle 'x0,y0' to
        'x1,y1' and stores it in the memory buffer pointed to by 'image_array'.
          The memory for 'image_array' must be allocated prior to this call.
          Upon returning from this routine, the first 2 bytes of the
          'image_array' buffer contain the image width, and the second 2 bytes
          contain the image height.  The remaining bytes in the 'image_array'
          buffer hold the image pixel data.







                                 Page: 27
                               
               The vsa_get_image routine is typically used in conjunction with
          the vsa_put_image routine for BitBLT operations.

Availability:  In VSA256 Graphics Library Version 3.0 and up.

Comments:      This routine clamps x0, y0, x1, and y1 to zero.  If any of
         these parameters are less than zero, vsa_get_image overrides them with
          zero and less than (x1-x0+1)*(y1-y0+1) pixels will be  loaded  into
          'image_array'. No limiting of y0 and y1 to YResolution-1 is performed
          so that off screen memory can be used as scratch pad area (see
          Sec. 5.3).

3.7.5 vsa_put_image
Prototype:    void vsa_put_image(int x0,int y0,unsigned char huge *image_array,
                                 int raster_op);

Description:   This routine displays the image defined in the 'image_array'
          buffer starting at screen coordinates 'x0,y0'.  The image
          width and height are determined by the first two 16 bit words of
          the 'image_array' buffer.  The 'raster_op' parameter determines how
          the data in the 'image_array' buffer are merged with the existing
          screen data, as defined below.

          raster_op     Function
           0            Replace existing data.
           1            AND with existing data.
           2            OR with existing data.
           3            XOR with existing data.
           4            Reserved .... Do Not Use !!
           5            Reserved .... Do Not Use !!
           6            Replace existing data only with non-zero pixels
                       (Sprites!).

          The vsa_put_image routine is typically used in conjunction with
          the vsa_get_image routine for BitBLT operations.

Availability:  In VSA256 Graphics Library Version 3.0 and up.
















                                 Page: 28
                               

4.0 NITTY GRITTIES

4.1 Registration Information
          If you find the VSA256 Graphics Library useful, a registration of $34
would be appreciated.  Registration brings with it MAJOR BENEFITS, as spelled
out in section 1.2, so look at the ORDER.TXT file and fill it out!

          Please fill out the Information About You and the Wish List sections,
and indicate the version number of the software you are presently using.  Send
check or money order to:

                                   Spyro Gumas
                            7910 W. Brookridge Drive
                              Middletown, MD  21769


                ******  COMPUSERVE   -   SWREG  ID: 5417  ******

If you are on CompuServe, you can register through SWREG. Just "GO SWREG", then
give  them  the registration ID: 5417. They will bill you $49.00 and I'll  send
you  both VSA256 and TIFF256 graphics Libraries (plus the goodies!). Please  do
fill  out and send me the information form so you can tell me what you want  in
the next revision.





























                                 Page: 29
                               
4.2 Software License
                       VSA256 Graphics Library, Version 4.0
            Copyright Spyro Gumas, 1992 - 1996.  All Rights Reserved.

   The VSA256 Graphics Library is a "shareware program" and is provided  at  no
charge to the user for evaluation. The essence of "user-supported" software  is
to provide  personal computer users with quality software without high  prices,
and yet  to  provide  incentive for programmers  to  continue  to  develop  new
products.  If  you  find this program useful and find that you  are  using  The
VSA256 Graphics Library and continue to use The VSA256 Graphics Library after
a reasonable trial period, you must make a registration payment of $34 to
Spyro Gumas. The $34 registration fee will license one copy for use on any one
computer  at any one time.  You must treat this software just like a book.   An
example  is  that this software may be used by any number of people and may  be
freely  moved  from one computer location to another, so long  as  there is  no
possibility of it being used at one location while it's being used at  another.
Just as a book cannot be read by two different persons at the same time.

You are free (and encouraged) to copy and distribute the VSA256 Graphics
Library if:

1)   It is not used as a component of another software library.
2)   No fee is charged for use, copying or distribution.
3)   It is distributed as is (preferably as VSA256.ZIP) and not modified in
     any way.

Furthermore, you are granted royalty free use of The VSA256 Graphics Library
executable code in any of your programs given that:

1)   You have registered your use of The VSA256 Graphics Library and paid the
     $34 registration fee.
2)   It is not used as a component of another software library.
3)   You visibly acknowledge the use of The VSA256 Graphics Library in your
     product in both the printed materials and the executable software with the
     following statement:

     "This software uses the VSA256 Graphics Library,
      Copyright Spyro Gumas, 1992 - 1996.  All Rights Reserved"


   Clubs and  user  groups may charge a nominal fee (not  to  exceed  $10)  for
expenses and  handling while distributing the VSA256 Graphics Library.   Anyone
distributing The VSA256 Graphics Library for any kind of remuneration must
first contact Spyro Gumas at the address below for authorization. This
authorization will be automatically granted to distributors recognized by the
(ASP) as adhering to its guidelines for shareware distributors, and such







                                 Page: 30
                               
distributors may begin offering The VSA256 Graphics Library immediately
(However Spyro Gumas must still  be advised so that the distributor can be kept
up-to-date with the latest version of The VSA256 Graphics Library.).

   Commercial users of The VSA256 Graphics Library must register  and  pay  for
their copies of The VSA256 Graphics Library within 30 days of first use or
their license  is  withdrawn.   Consult the file ORDER.TXT  for  more
information  or contact Spyro Gumas.

4.3 Disclaimer
  Users of The VSA256 Graphics Library must accept this disclaimer of warranty:
The VSA256 Graphics Library is supplied as is.  The author disclaims all
warranties, expressed or implied, including, without limitation, the warranties
of merchantability and of fitness for any purpose. The author assumes no
liability for damages, direct or consequential, which may result from the use
of The VSA256 Graphics Library.  In no event shall the author's liability for
any damages ever exceed the price paid for the license to use The VSA256
Graphics Library, regardless of the form of the claim.  The person using The
VSA256 Graphics Library bears all risk as to the quality and performance of
this software.

4.4 Technical Support
  If you have any questions or comments about the VSA256 Graphics Library,
please write me at:

                                   Spyro Gumas
                            7910 W. Brookridge Drive
                              Middletown, MD  21769

Or, contact me on EMAIL!

                      CompuServe: 71064,1571
                      Internet: 71064.1571@compuserve.com



And Make Sure to visit my WEB PAGE at:

              http://ourworld.compuserve.com/homepages/blueberry














                                 Page: 31
                               

5.0 APPLICATION NOTES

5.1 Using Triangles
  Starting with VSA256 V4.0, the programmer can turn off clipping specifically
for triangle drawing operations via the vsa_set_triangle_clip_mode routine.
You may ask "why is this a reasonable thing?".
  One of the intended uses for the vsa_shaded_triangle routine is to use lots
of small shaded triangles to form large 3D shaped surfaces.  The process of
breaking down the large surface into small patches is called "tessellation" (I
think).  If you actually go to the effort of writing software to do this, maybe
using Bezier curves or B-splines, you could also clip the large surface
dimensions to the clipping window prior to the tessellation process.  If you do
so, and turn off triangle clipping, you will eliminate the overhead of having
to clip test the hundreds of tiny triangles that are mostly within the window
anyway.  Turning triangle clipping off doubles the drawing speed of 30 x 30 x
42 pixel triangles using vsa_shaded_triangle.

5.2 Page Flipping
  Ever since VSA256 V1.0, the vsa_set_display_start routine has been available
for page flipping (Ping-Pong Buffering) of the video memory.  But I'll be the
first to admit that using this feature was not intuitive.  You had to turn off
all clipping and then draw in off screen Y coordinates to get to the second
page... what a mess.
  VSA256 V4.0 cleans up all of this confusion.  With vsa_set_draw_page and
vsa_set_view_page, the programmer no longer has to think about the details.
After vsa_init, DRAW_PAGE and VIEW_PAGE both = 0. The programmer can follow the
following sequence for professional looking results.

- vsa_set_draw_page(1);                  // flip to video page 1 for drawing.
- vsa_set_color(0);                      // set to background color.
- vsa_move_to(0,0);
- vsa_rect_fill(XResolution-1,YResolution-1);   // Clear page 1.
- BlahBlahBlah                           // Do all of your drawing.
- vsa_wait_vsync();                      // optional.
- vsa_set_view_page(1);                  // Display page 1 on screen.
- vsa_set_draw_page(0);                  // flip to video page 0 for drawing.
- repeat clearing and drawing into vid page 0 now.

5.3 Using Off Screen Video Memory
  You may find it convenient to create small bit maps (Sprites?) and store them
off screen in undisplayed video memory,  for instance all of the cute little
buttons used in a GUI program. Then you can use vsa_get_image to snatch them up
and vsa_put_image to plop them down somewhere on the displayable screen. This
would be of particular interest to a programmer who is fresh out of extra
memory to allocate for the storage of these bitmaps.







                                 Page: 32
                               
  To do this, all you need is to set the viewport 'bottom' value far enough
below the bottom of the displayable video memory to leave room for your
bitmaps. For example, say you are running in 800x600 video mode and you have 25
bit mapped buttons of 32x32 size each which you would like to predraw and
store. Set the clipping viewport to include pixel row 631 with
vsa_set_viewport(0,0,799,631).  Now go ahead and draw your buttons in the space
between 0,600 and 799,631.  The display will only show the area between 0,0 and
799,599 ... your buttons won't show. But they are there and you can access them
with vsa_get_image and you can display them with vsa_put_image.  Pretty cool
huh?

5.4 Expanding the VSA_FONT Character Set
  Starting with VSA256 V4.0 you can change the number of possible characters in
the font array.  If you want to increase the total number of characters, just
change the '96' dimension in the 'ASC[96][72]' declaration in the VSA_FONT.H
file to the new desired number of characters.  Then make sure to fill out the
remainder of the array.
  This new capability is a result of strong international pressures.  Now you
folks can go and customize your own, large, international font sets.  How about
if you share these new VSA_FONT.H files with me and I can make them available
to all users via my Web page?


6.0 GRAPHICS LIBRARY EXTENSIONS

  The VSA256 Graphics Library is a base library which is supported by Graphics
Library Extensions (GLEs) for more specialized tasks.  These GLEs are typically
shareware and new ones are developed periodically.

6.1 THE VSA256 GLE DEVELOPERS PROGRAM

  I want to encourage people to write VSA256 GLEs.  The reason is simple.  As
the number of available GLEs grows, so does the applicability of the VSA256
Graphics Library to various software applications.  As this happens, the demand
for the VSA256 Graphics Library grows, and the better off I become.  For this
reason, I started the VSA256 GLE Developers Program (VGDP).

What Is It?    The VGDP is an incentive arrangement between myself and GLE
developers by which I get developers to write VSA256 GLEs.

How's It Work?    A developer writes a VSA256 GLE and sends it to me.  If it
adds a unique capability and it meets my quality standards, it is added to the
list of goodies that I offer to registered users. When a user registers for the
VSA256 Graphics Library, in addition to the normal stuff, I also send him the
VSA256 GLE.  If he likes your GLE, he can register for it by sending you
payment.







                                 Page: 33
                               
What's In It For Me?    Clearly I get a lot of benefits.  1) The overall demand
for the VSA256 Graphics Library goes up.  2) I get to use your GLE as an
incentive for people to register for my software.  3) I don't have to write all
of the VSA256 related GLEs out there.  4) I get to meet a lot of interesting
people doing really interesting things.

What's In It For You?    You wouldn't do this unless you also benefit, right?
1)  Exposure of your product. The VSA256 Graphics Library has been around since
    1991 and has developed quite a following.
    -  The VSA256 Graphics Library has been featured in two books by SAMs
       Publishing  (Tricks of the Graphics Gurus and PC Graphics Unleashed).
    -  New GLEs will receive exposure in any subsequent book deals.
    -  Your GLE gets exposure through the flyers I send out.
    -  I feature each of the existing VSA256 GLEs on my home page.
2)  Ready made market.  The VGDP lets you take advantage of an existing base of
    people already programming with the VSA256 Graphics Library.  If you have a
    useful GLE, they will be anxious to get there hands on it.
3)  The VGDP is a helping hand in getting your shareware business up and
    running.  You can start from scratch, but it sure is easier to ride on the
    coat tails of a successful product.

A suggestion - A submission to the VGDP should be a self contained, preferably
zipped package which is ready to go to the user and includes as a minimum:
-  The Library File
-  Any Include Files
-  Demo Program
-  Documentation File
-  Order Form (So they can send you registration payments)

Some possible VSA256 GLEs:
-  A GUI
-  A really robust 3D library
-  Integrating Sound into the VSA256 environment
-  How about a 3d fly by phase shifting Doppler corrected sound modeler
-  Fancy 3D stuff
-  Fancy Text Manipulation Stuff
-  Various Image readers.
















                                 Page: 34
                               

6.2 EXISTING GRAPHICS LIBRARY EXTENSIONS


TIFF256 Graphics Library Extension 4.0 - This library extension provides
functions which operate with Tagged Image File Format (TIFF) images. With these
functions, you can traverse the image file, extract image information, and
display the images as part of your own program.  You can also modify the TIFF
images and write them back to TIFF files.  Furthermore, any image that you
generate with VSA256 can be saved as a TIFF file.  The image types supported
include Bilevel, Grayscale, Palette Color and RGB True Color.  Adaptive Color
Palette generation is supported for 24 bit images.  This makes most True Color
images show up undistorted by the 256 color limitation.  Compressed TIFF files
are also supported for reading and writing.  The full function version of the
TIFF256 Graphics Library Extensions is shareware, available from the same place
that you got the VSA256 Graphics Library.

CBTMouse API Library 1.0 - New from CyberBase Technologies, Inc., this library
adds complete mouse interaction to your graphics applications.   These guys go
all out to make mouse driven graphics programming a breeze.  Functions provided
include initialization, displaying and hiding mouse, reading position, setting
position, reading button status, working within bounding boxes, changing cursor
color and size, and waiting for various mouse inputs. You get a very functional
version of this library when you register for the VSA256 Graphics Library.  The
full up library (version 1.0) is shipped by CyberBase Technologies, Inc. upon a
nominal registration fee.

VSA3D Library 1.0 - This library lets you write 3D applications. What ever your
interests, Mechanical Design, Architecture, Interior Design, Space Widgets, you
name it, you can do it.  Functions provided let you add and delete objects from
a display list, set the view point, and perform 3D transformations including
scale, offset, and rotation.  Select the drawing mode for the 3D objects from
Wireframe, Solid, or Gouraud (smooth) Shaded. You get a very functional version
of this library when you register for the VSA256 Graphics Library.



















                                 Page: 35
                               

7.0 APPENDIX

7.1 VSA.H Include File
/*.................................. VSA.H ................. 2-24-96 .......*/
/* This file declares the VSA256 Graphics Library functions and global      */
/* parameters used throughout the graphics routines.                        */
/*                                                                          */
/*                               VERSION 4.0                                */
/*                                                                          */
/*         Copyright Spyro Gumas, 1992 - 1996.  All Rights Reserved.        */
/*..........................................................................*/

/*..........................................................................*/
/*                    External Function Prototypes                          */
/*..........................................................................*/

extern unsigned  far vsa_set_svga_mode( unsigned );
extern unsigned  far vsa_get_svga_mode( unsigned far * );
extern unsigned  far vsa_set_display_start( unsigned, unsigned );
extern unsigned  far vsa_get_display_start( unsigned far *,unsigned far * );
extern unsigned  far vsa_init( unsigned );
extern void      far vsa_set_color( unsigned );
extern unsigned  far vsa_get_color(void);
extern void      far vsa_set_text_color( unsigned );
extern unsigned  far vsa_get_text_color(void);
extern void      far vsa_set_text_cursor_mode( unsigned );
extern unsigned  far vsa_get_text_cursor_mode(void);
extern void      far vsa_set_text_cursor( int, int);
extern void      far vsa_get_text_cursor( int far *, int far *);
extern void      far vsa_set_text_scale(float,float);
extern void      far vsa_get_text_scale(float far *,float far *);
extern void      far vsa_set_viewport( int, int, int, int);
extern void      far vsa_get_viewport(int far *,int far *,int far *,int far*);
extern void      far vsa_set_clip_mode(  unsigned );
extern unsigned  far vsa_get_clip_mode(void);
extern void      far vsa_set_triangle_clip_mode(int mode);
extern int       far vsa_get_triangle_clip_mode(void);
extern void      far vsa_write_string( int, int, int, char far * );
extern void      far vsa_write_string_alt( char far * );
extern void      far vsa_read_color_register( unsigned, unsigned char far *,
                                   unsigned char far *,unsigned char far *);
extern void      far vsa_write_color_register( unsigned, unsigned char,
                                               unsigned char,unsigned char );
extern void far vsa_read_color_block(unsigned, unsigned,unsigned char far * );
extern void far vsa_write_color_block(unsigned, unsigned,unsigned char far *);
extern void far vsa_move_to( int, int);
extern void far vsa_set_pixel( int, int);
extern unsigned far vsa_get_pixel( int, int);
extern void far vsa_line_to( int, int);
extern void far vsa_triangle( int, int, int, int, int, int);
extern void far vsa_triangle_fill( int, int, int, int, int, int);
extern void far vsa_rect_fill( int, int);
                                 Page: 36
                               
extern void far vsa_rect( int, int);
extern unsigned long far vsa_image_size( int, int, int, int);
extern void far vsa_get_image( int, int, int, int,unsigned char huge * );
extern void far vsa_put_image( int, int,unsigned char huge *, unsigned);
extern void far vsa_h_line( int, int, int);
extern void far vsa_v_line( int, int, int);
extern void far vsa_raster_line( int, int, int, unsigned char far *);
extern void far vsa_get_raster_line( int, int, int,unsigned char far *);
extern void far vsa_gouraud_line( int, int, int, int, int);
extern void far vsa_shaded_triangle(int,int,int,int,int,int,int,int,int);
extern void far vsa_wait_hsync( void );
extern void far vsa_wait_vsync( void );
extern void far vsa_about( void );
extern void vsa_set_draw_page(int);
extern int  vsa_get_draw_page(void);
extern void vsa_set_view_page(int);
extern int  vsa_get_view_page(void);

/*..........................................................................*/
/*                    External Parameter Declarations                       */
/*..........................................................................*/
extern unsigned far XResolution, far YResolution;
extern unsigned far XCharResolution, far YCharResolution;
extern unsigned char far XCharSize, far YCharSize;
extern unsigned char far BitsPerPixel;
extern int far XLeft, far XRight, far YTop, far YBottom;
extern float far Text_X_Scale, far Text_Y_Scale;
extern int far VSA_ATI_COLOR;

























                                 Page: 37
                               

7.2 VSA_FONT.H Include File
/*............................... VSA_FONT.H .............. 2-17-96 ........*/
/*    This is the font file for the VSA256 Graphics Library.  The basic     */
/*  font size is set by the XCharBase and YCharBase values defined at the   */
/*  top of this file.  This include file gives you the ability to fully     */
/*  customize your fonts! Feel free to edit the font vertex lists to be as  */
/*  personalized as possible.  Read on to see how it works.                 */
/*                                                                          */
/*   ASC[M][N] is a 2 dimensional array.  The M index selects one of 96     */
/* possible characters and corresponds to the printable ASCII character     */
/* codes from 32 to 127. (M = 0 selects ASCII character code 32 ... a space,*/
/* M = 95 selects ASCII character code 127 ... DEL)                         */
/*   For any given value of M, the N index steps through the vertex list    */
/* for that character.  Each vertex takes up 3 locations.  The first of     */
/* the 3 values is the blank code. A blank code of 0 means start a new line */
/* segment (equivalent to "move_to").  A blank code of 1 means continue     */
/* drawing (equivalent to "line_to").  A blank code of 255 means END of     */
/* vertex list. You MUST end each vertex list this way!                     */
/*   The next two values are x and y coordinates relative to the top left   */
/* corner of the character cell.  The x and y values should never be more   */
/* than XCharBase-1 and YCharBase-1 respectively.  When the blank code is   */
/* 255, the x and y values are ignored.  A maximum of 23 verticies plus an  */
/* END vertex are allowed per character.  Overrunning this limit will       */
/* probably cause your PC to go woopie.                                     */
/*                                                                          */
/*   Starting with version 4.0 of this library, the user can change the     */
/* number of possible characters in the font array.  If you want to         */
/* increase the total number of characters, just change the '96' dimension  */
/* below in the 'ASC[96][72]' declaration to the new desired number of      */
/* characters.  Then make sure to fill out the remainder of the array.      */
/*                                                                          */
/*                               VERSION 4.0                                */
/*                                                                          */
/*        Copyright Spyro Gumas, 1992 - 1996.  All Rights Reserved.         */
/*..........................................................................*/

/*..... 12-14-94   Added 'far' to declarations.                        .....*/
/*.....  2-17-96   Now user can change '96' dimension of ASC array.    .....*/

unsigned far XCharBase = 8, far YCharBase = 16;
unsigned char far ASC[96][72]={... Array initialization not printed here  ...
                               ... for brevity.  See VSA_FONT.H file for  ...
                               ... details.                               ...









                                 Page: 38
